/**
 * 版权所有(C)，上海勾芒信息科技，2017，所有权利保留。
 * 
 * 项目名：	cards-web
 * 文件名：	WxComponentAuthorService.java
 * 模块说明：	
 * 修改历史：
 * 2017年4月21日 - Debenson - 创建。
 */
package me.chanjar.weixin.component.api;

import me.chanjar.weixin.common.exception.WxErrorException;
import me.chanjar.weixin.component.bean.author.WxApiQueryAuthResult;
import me.chanjar.weixin.component.bean.author.WxAuthorizerAccessToken;
import me.chanjar.weixin.component.bean.author.WxAuthorizerOption;
import me.chanjar.weixin.component.bean.author.WxGetAuthorizerInfoResult;

/**
 * 微信开放平台授权相关服务。
 * 
 * @author Debenson
 * @since 0.1
 */
public interface WxCompAuthorService {

  /**
   * 获取预授权码pre_auth_code, 不强制刷新pre_auth_code
   *
   * @see #getPreauthorCode(boolean)
   */
  String getPreauthorCode() throws WxErrorException;

  /**
   * <pre>
   * 获取预授权码pre_auth_code，本方法线程安全
   *
   * 另：本service的所有方法都会在pre_auth_code过期是调用此方法
   *
   * 程序员在非必要情况下尽量不要主动调用此方法
   *
   * 详情请见: https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&id=open1453779503&token=f4e6cc754f4b06bd2a86158a0f4353bc3b8d3454&lang=zh_CN
   * </pre>
   *
   * @param forceRefresh
   *          强制刷新
   */
  String getPreauthorCode(boolean forceRefresh) throws WxErrorException;

  /**
   * 取得用户进入第三方平台授权页的地址
   * 
   * @return
   * @throws WxErrorException
   */
  String getComponentLoginPageUrl() throws WxErrorException;

  /**
   * 使用授权码换取公众号或小程序的接口调用凭据和授权信息
   * 
   * @param authorizationCode
   *          授权code,会在授权成功时返回给第三方平台，详见第三方平台授权流程说明
   * @return 授权信息
   * @throws WxErrorException
   */
  WxApiQueryAuthResult queryAuthor(String authorizationCode) throws WxErrorException;

  /**
   * 获取（刷新）授权公众号或小程序的接口调用凭据（令牌） <br>
   * 该API用于在授权方令牌（authorizer_access_token）失效时，可用刷新令牌（authorizer_refresh_token）获取新的令牌。请注意，此处token是2小时刷新一次，开发者需要自行进行token的缓存，避免token的获取次数达到每日的限定额度。缓存方法可以参考：http://mp.weixin.qq.com/wiki/2/88b2bf1265a707c031e51f26ca5e6512.html
   * 
   * @param authorizerAppId
   *          授权方appid
   * @param authorizerRefreshToken
   *          授权方的刷新令牌，刷新令牌主要用于第三方平台获取和刷新已授权用户的access_token，只会在授权时刻提供，请妥善保存。一旦丢失，只能让用户重新授权，才能再次拿到新的刷新令牌
   * @return
   * @throws WxErrorException
   */
  WxAuthorizerAccessToken getAuthorizerAccessToken(String authorizerAppId,
      String authorizerRefreshToken) throws WxErrorException;

  /**
   * 获取授权方的帐号基本信息
   * 
   * @param authorizerAppId
   *          授权方appid
   * @return
   * @throws WxErrorException
   */
  WxGetAuthorizerInfoResult getAuthorizerInfo(String authorizerAppId) throws WxErrorException;

  /**
   * 获取授权方的选项设置信息
   * 
   * @param authorizerAppId
   *          授权公众号或小程序的appid
   * @param optionName
   *          选项名称
   * @return
   * @throws WxErrorException
   */
  WxAuthorizerOption getAuthorizerOption(String authorizerAppId, String optionName)
      throws WxErrorException;

  /**
   * 设置授权方的选项设置信息
   * 
   * @param authorizerAppId
   *          授权公众号或小程序的appid
   * @param optionName
   *          选项名称
   * @param optionValue
   *          设置的选项值
   * @throws WxErrorException
   */
  void setAuthorizerOption(String authorizerAppId, String optionName, String optionValue)
      throws WxErrorException;
}
